home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / SELECTIO.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  11.3 KB  |  340 lines
  1. package sub_arctic.input;
  2.  
  3. import sub_arctic.lib.interactor;
  4. import sub_arctic.lib.manager;
  5. import sub_arctic.lib.sub_arctic_error;
  6.  
  7. import java.util.Vector;
  8.  
  9. /** 
  10.  * Positional dispatch agent for maintaining a currently selected set.  This 
  11.  * agent dispatches inputs under the selectable input protocol and maintains
  12.  * a currently selected object set.  Objects can be placed in the set by 
  13.  * clicking on them using a Macintosh style interaction where simple clicks
  14.  * make objects the single selection, and clicks with the shift key held down
  15.  * add to the set.
  16.  *
  17.  * @see sub_arctic.input.selectable
  18.  * @author Scott Hudson
  19.  */
  20. public class selection_agent_class extends dispatch_agent {
  21.  
  22.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  23.  
  24.   /** Simple constructor */
  25.   public selection_agent_class()
  26.     {
  27.       _selection_set = new Vector();
  28.     }
  29.  
  30.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  31.  
  32.   /** The currently selected set.  This vector contains selectable objects. */
  33.   protected Vector _selection_set;
  34.  
  35.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  36.  
  37.   /** Number of objects currently selected */
  38.   public int num_selected() { return _selection_set.size(); }
  39.  
  40.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  41.  
  42.   /** 
  43.    * Retrieve the selected object at the given index in the currently selected 
  44.    * set.
  45.    * @param int index the index of the desired element.
  46.    * @return selectable the desired element
  47.    */
  48.   public selectable selected_set_item(int index) 
  49.     { 
  50.       if (index < 0 || index >= num_selected())
  51.     throw new sub_arctic_error("Index into selection set out of range (" +
  52.                    index + ")");
  53.  
  54.       return (selectable)_selection_set.elementAt(index);
  55.     } 
  56.  
  57.    //had:
  58.    //* @exception index_bounds if the given index is out of range.
  59.  
  60.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  61.  
  62.   /** 
  63.    * Clear the selection set to empty.
  64.    *
  65.    * @param event  evt       the event which "caused" the clear.
  66.    * @param Object user_info the user information that should be passed to 
  67.    *                         objects dropping out of the selection set.
  68.    */
  69.   public void clear_selection_set(event evt, Object user_info)
  70.     {
  71.       /* walk down the set and tell everyone */
  72.       for (int i = 0; i < _selection_set.size(); i++)
  73.     {
  74.       inform_removal((selectable)_selection_set.elementAt(i),evt,user_info);
  75.     }
  76.  
  77.       /* clear the list */
  78.       _selection_set.removeAllElements();
  79.     }
  80.  
  81.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  82.  
  83.   /**
  84.    * Set the selection set to the given single element.  Objects have the 
  85.    * option of rejecting selection (by returning false from select(), in 
  86.    * which case this routine returns false and the selection set is left 
  87.    * as is.
  88.    *
  89.    * @param selectable obj       the object being selected
  90.    * @param event      evt       the event which "caused" the selection.
  91.    * @param Object     user_info the user information that should be passed to 
  92.    *                             objects added and dropped out of the selection 
  93.    *                             set.
  94.    * @return boolean indicating if the object accepted the selection.
  95.    */
  96.   public boolean set_selection(selectable obj, event evt, Object user_info)
  97.     {
  98.       int indx;
  99.  
  100.       /* see if our addition is already in the set, if not tell it about add */
  101.       indx = find_selection(obj);
  102.       if (indx == -1)
  103.     {
  104.       /* if it rejects the add we leave things alone and bail out */
  105.       if (!inform_addition(obj,evt,user_info))
  106.         return false;
  107.     }
  108.  
  109.       /* walk down the set and tell everyone accept the object */
  110.       for (int i = 0; i < _selection_set.size(); i++)
  111.     {
  112.       /* tell it its gone unless we are going to put it right back in */
  113.       if (i != indx)
  114.         inform_removal((selectable)_selection_set.elementAt(i), evt, 
  115.                                  user_info);
  116.     }
  117.  
  118.       /* clear the list and put in our one element */
  119.       _selection_set.removeAllElements();
  120.       _selection_set.addElement(obj);
  121.  
  122.       return true;
  123.     }
  124.  
  125.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  126.  
  127.   /** 
  128.    * Return the index of the given object in the currently selected object
  129.    * set or -1 if the object is not selected.
  130.    *
  131.    * @param selectable obj the object we are inquiring about.
  132.    * @return int the index of the object in the currently selected object set
  133.    *             or -1 if it is not currently selected.
  134.    */
  135.   public int find_selection(selectable obj)
  136.     {
  137.       return _selection_set.indexOf(obj);
  138.     }
  139.  
  140.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  141.  
  142.   /**
  143.    * Add the given object to the selection set.  Objects have the 
  144.    * option of rejecting selection (by returning false from select(), in 
  145.    * which case this routine returns false and the selection set is left 
  146.    * as is.
  147.    *
  148.    * @param selectable obj       the object being selected
  149.    * @param event      evt       the event which "caused" the selection.
  150.    * @param Object     user_info the user information that should be passed to 
  151.    *                             object added to the selection set.
  152.    * @return boolean indicating if the object accepted the selection.
  153.    */
  154.   public boolean add_to_selection_set(
  155.     selectable obj, 
  156.     event      evt, 
  157.     Object     user_info)
  158.     {
  159.       /* only do something if the object in question is not already there */
  160.       if (find_selection(obj) == -1)
  161.     {
  162.       /* put it in and let the object know */
  163.       if (inform_addition(obj, evt, user_info))
  164.         {
  165.           _selection_set.addElement(obj);
  166.           return true;
  167.         }
  168.       else
  169.         return false;
  170.     }
  171.  
  172.       /* already there so we accept the dispatch */
  173.       return true;;
  174.     }
  175.  
  176.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  177.  
  178.   /**
  179.    * Remove the given object to the selection set.  False is returned if
  180.    * the object is not in the selection set, or if the object's unselect()
  181.    * method returns false (however, the object is always removed from the 
  182.    * selection set).
  183.    *
  184.    * @param selectable obj       the object being deselected
  185.    * @param event      evt       the event which "caused" the deselection.
  186.    * @param Object     user_info the user information that should be passed to 
  187.    *                             object dropped out of the selection set.
  188.    * @return boolean indicating if the object accepted the selection.
  189.    */
  190.   public boolean remove_from_selection_set(
  191.     selectable obj, 
  192.     event      evt,
  193.     Object     user_info)
  194.     {
  195.       int indx;
  196.  
  197.       /* only do something if the object in question is there */
  198.       indx = find_selection(obj);
  199.       if (indx != -1)
  200.     {
  201.       /* take it out and let the object know */
  202.       _selection_set.removeElementAt(indx);
  203.       return inform_removal(obj, evt, user_info);
  204.     }
  205.  
  206.       return false;
  207.     }
  208.  
  209.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  210.  
  211.   /** 
  212.    * Indicate which events we are interested in seeing.  We are only 
  213.    * interested in presses of the mouse button.
  214.    * 
  215.    * @param event evt the event we are testing.
  216.    * @return boolean indicating whether we want to see the event.
  217.    */
  218.   public boolean event_is_useful(event evt)
  219.     {
  220.       return evt.id() == event.MOUSE_DOWN;
  221.     }
  222.  
  223.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  224.  
  225.   /**
  226.    * Do the work of informing an object that it has been added to the currently
  227.    * selected object set.  Returns the result of the select() call on the 
  228.    * object.  Note: this routine does not put the object in the set.
  229.    *
  230.    * @param selectable  obj       the object we are informing.
  231.    * @param event       evt       the event "causing" the selection.
  232.    * @param Object      user_info the user info that should be passed to the 
  233.    *                              object.
  234.    * @return boolean which was the result of the object's select() method.
  235.    */
  236.   protected boolean inform_addition(
  237.     selectable  obj, 
  238.     event       evt, 
  239.     Object      user_info)
  240.     {
  241.       /* put the event into the proper coords */
  242.       if (obj instanceof interactor)
  243.     evt.global_to_local((interactor)obj);
  244.       else
  245.     evt.reset_to_global();
  246.  
  247.       /* tell the object */
  248.       return obj.select(evt, user_info);
  249.     }
  250.  
  251.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  252.  
  253.   /**
  254.    * Do the work of informing an object that it has been removed from the 
  255.    * currently selected object set.  Returns the result of the unselect() call 
  256.    * on the object.  Note: this routine does not remove the object from the set.
  257.    *
  258.    * @param selectable  obj       the object we are informing.
  259.    * @param event       evt       the event "causing" the deselection.
  260.    * @param Object      user_info the user info that should be passed to the 
  261.    *                              object.
  262.    * @return boolean which was the result of the object's unselect() method.
  263.    */
  264.   protected boolean inform_removal(
  265.     selectable  obj, 
  266.     event       evt, 
  267.     Object      user_info)
  268.     {
  269.       /* put the event into the proper coords */
  270.       if (obj instanceof interactor)
  271.     evt.global_to_local((interactor)obj);
  272.       else
  273.     evt.reset_to_global();
  274.  
  275.       /* tell the object */
  276.       return obj.unselect(evt, user_info);
  277.     }
  278.  
  279.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  280.  
  281.   /** 
  282.    * Attempt to dispatch an event with this agent.  Mouse presses with the 
  283.    * shift key held down add to the currently selected object set.  Plain
  284.    * presses replace the currently selected object set with a single object.
  285.    *
  286.    * @param event      evt        the event we are trying to dispatch
  287.    * @param Object     user_info  the user info value to pass with the dispatch
  288.    * @param interactor to_obj     the object to dispatch to.
  289.    * @param int        seq_num    the sequence number of this event.
  290.    * @return boolean indicating whether the event was consumed.
  291.    */
  292.   public boolean dispatch_event(
  293.     event      evt,
  294.     Object     user_info,
  295.     interactor to_obj,
  296.     int        seq_num)
  297.     {
  298.        selectable sel_obj;
  299.  
  300.        /* if the object doesn't want selection bail out now */
  301.        if (!(to_obj instanceof selectable)) return false;
  302.  
  303.        sel_obj = (selectable)to_obj;
  304.  
  305.        /* is the shift key is down? */
  306.        if ((evt.modifiers() & event.SHIFT_MASK) != 0) 
  307.      {
  308.        /* if object is already in the selection set remove it */
  309.        if (find_selection(sel_obj) != -1)
  310.          return remove_from_selection_set(sel_obj, evt, user_info);
  311.        else
  312.          /* otherwise add object to selection */
  313.          return add_to_selection_set(sel_obj, evt, user_info);
  314.      }
  315.        else
  316.      {
  317.        /* set object as sole selection */
  318.        return set_selection(sel_obj, evt, user_info);
  319.      }
  320.     }
  321.  
  322.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  323. }
  324. /*=========================== COPYRIGHT NOTICE ===========================
  325.  
  326. This file is part of the subArctic user interface toolkit.
  327.  
  328. Copyright (c) 1996 Scott Hudson and Ian Smith
  329. All rights reserved.
  330.  
  331. The subArctic system is freely available for most uses under the terms
  332. and conditions described in 
  333.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  334. and appearing in full in the lib/interactor.java source file.
  335.  
  336. The current release and additional information about this software can be 
  337. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  338.  
  339. ========================================================================*/
  340.